<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<meta name="description" content="ssht: spin spherical harmonic transforms" />
<meta name="keywords" content="ssht, spherical, harmonics, spherical
harmonics, sphere, transforms, fourier, fast, algorithms, mcewen, wiaux" />
<meta name="author" content="Jason McEwen / Design by Andreas Viklund - http://andreasviklund.com/" />
<link rel="stylesheet" type="text/css" href="style.css" title="1024px style" media="screen,projection" />
<title>ssht</title>
</head>

<body>
<div id="wrap">

  
<!--------------------------- HEADER --------------------------->
<div id="header">

  <p id="toplinks">
  <a href="#introduction">Introduction</a> |
  <a href="#routines">Routines</a> |
  <a href="#installation">Installation</a> |
  <a href="#documentation">Source</a> |
  <a href="#matlab">Matlab</a> |
  <a href="#python">Python</a> |
  <a href="#download">Download</a> |
  <a href="#referencing">Referencing</a> |  
  <a href="#version">Version</a> |
  <a href="#license">License</a> |
  <a href="#authors">Authors</a> 
  </p>

  <table border="0" cellspacing="0">
    <tr>
      <td width=200 height=142 align="right" valign="top">
	<img src="images/logo.jpg" width="140" height="140" border=0> 
      </td>
      <td width=500 align="left" valign="center">
	<h1 class="title">ssht</h1>
	<p id="slogantitle">Spin spherical harmonic transforms</p>
      </td>			
    </tr>
  </table>

</div>


<!--------------------------- SIDEBAR --------------------------->
<div id="sidebar">
   
<h2>News</h2>

<ul>
<li><strong>April 2018</strong><br />
Release of SSHT 1.2b1 (support to link to C++).
</li>
<li><strong>April 2017</strong><br />
Release of SSHT 1.1b1 (python support).
</li>
<li><strong>October 2011</strong><br />
Public release of SSHT 1.0b1 (first beta).
</li>
<li><strong>May 2011</strong><br />
Private release of SSHT 0.2, including fast adjoint algorithms.
</li>
<li><strong>March 2011</strong><br />
Private release of SSHT 0.1.
</li>
</ul>

</div>


<!--------------------------- CONTENT --------------------------->
<div id="content">

<!--------------------------------------------------------------->
<a name="introduction"><h2>Introduction</h2></a>

  <p>
  The <strong>SSHT</strong> code provides functionality to perform fast and exact
  spin spherical harmonic transforms based on the sampling theorem on the
  sphere derived in our paper:
  <i><a href="http://www.jasonmcewen.org/publications.html#mcewen:fssht">A
  novel sampling theorem on the sphere</a> </i>
  (<a href="http://arxiv.org/abs/1110.6298">ArXiv</a>
  | <a href="http://dx.doi.org/10.1109/TSP.2011.2166394">DOI</a>).

  In some applications, adjoint forward and inverse spherical harmonic
  transforms are also required (for example, when solving convex
  optimisation problems).  We provide functionality to perform
  fast and exact adjoint transforms, based on the fast algorithms
  derived in our paper: 
  <i><a href="http://www.jasonmcewen.org/publications.html#mcewen:css2">Sparse image reconstruction on the sphere: implications of a new sampling theorem</a></i>
  (<a href="http://arxiv.org/abs/1205.1013">ArXiv</a>
  | <a href="http://dx.doi.org/10.1109/TIP.2013.2249079">DOI</a>).

  <p>
  This documentation outlines the various harmonic transforms
  supported in <strong>SSHT</strong>, before describing installation details and
  documenting the C, Fortran and Matlab source code.  Reference,
  version, and license information then follows.
  
  For an overview see the <a href="../README.md">README.txt</a>
  file.

<!--------------------------------------------------------------->  
<a name="routines"><h2>Spin spherical harmonic transform routines</h2></a>

  <p> Routines are provided to compute forward and inverse transforms
  using our optimal sampling (the MW routines).  An extension of our
  sampling theorem to a sub-optimal but diametrically symmetric
  sampling, which is important for certain applications, is also
  provided (the MWSS routines).  For the MW and MWSS routines we also
  provide fast algorithms to perform adjoint forward and inverse
  transforms.

  <p> We also provide optimal routines to perform spherical harmonic
  transforms using Gauss-Legendre quadrature (the GL routines),
  although these are slower than the MW routines.

  <p> Finally, we provide routines to perform transforms based on the
  quadrature of Driscoll & Healy (the DH routines).  Note that we do
  NOT implement the fast Driscoll & Healy algorithms (which may be
  found in s2kit) but simply apply the quadrature rule to implement a
  simple algorithm based on a separation of variables, hence these
  routines are slower still.

  <p> All of these transforms correspond to sampling theorems on the
  sphere, with exact forward and inverse transforms for band-limited
  signals.  In practice reconstruction accuracy is limited by machine
  precision.  For all of the algorithms we find maximum reconstruction
  errors are of the order 10^(-10) or considerably smaller.  Please
  set our paper for a discussion of the various algorithms implemented
  in the SSHT package and for a comparison of their performance.


<!--------------------------------------------------------------->  
<a name="installation"><h2>Installation</h2></a>

  <p> The <strong>SSHT</strong> package contains both C and Fortran 90
  implementations.  The C version is recommended since it is faster
  (due to more efficient memory addressing) and, in addition to the MW
  routines, it also contains the MWSS, GL and DH routines described <a
   href="#routines">above</a>.  Furthermore, fast adjoint algorithms
  are provided in the C implementation only.  The Fortran version
  contains the core MW routines and additional development and testing
  routines.  Furthermore, a Matlab interface to the C implementation
  is provided.

  <h4>Dependencies</h4>

  <p> <strong>SSHT</strong> requires only the <a
 href="http://www.fftw.org/">FFTW</a> package.  Obviously suitable C and
 Fortran 90 compilers will be required to build the respective
 implementations.  Both C and Matlab mex compilers will be required
 to build the Matlab interface to the C implementation.  The python interface requires <a href="http://www.numpy.org/">numpy</a> and, in addition, the demos require <a href="http://matplotlib.org/">matplotlib</a>.


  <h4>Compiling</h4>

  <p> Makefiles are provided to build the code.  By default the C <a
  href="../makefile">makefile</a> will be assumed, unless the Fortran
  <a href="../makefile_f90">makefile_f90</a> is explicitly specified by passing
  the filename to make using the following command:

  <pre> >> make -f makefile_f90</pre>

  <p>
  Hereafter we consider the C makefile, although the following
  commands also apply to the Fortran makefile (with the exception of
  the Matlab interface).  Before compiling you will need to edit the
  makefile to specify your compiler and to link with the appropriate libraries.

  <p> Once you have set the makefile up for your system,
  <strong>SSHT</strong> may be compiled by running:

  <pre> >> make all</pre> 

  <p> This will build the library, test program and Matlab interface.
  If your system is configured to build all of these components then
  you are done.  If you prefer to build only a subset of these
  components then read on.

  <p> You may alternatively build the individual components of
  <strong>SSHT</strong>.  To build the library only run:
  <pre> >> make lib</pre> 
  <p> To build the test program run:
  <pre> >> make test</pre> 
  <p> To build the Matlab interface run (which will also build the
  library if it has not already been built):
  <pre> >> make matlab</pre>
  <p> To build the python interface run:
  <pre> >> python setup.py build_ext --inplace</pre>


  <h4>Testing</h4>

  <p> Run the test program to verify your installation.  A default
  test may be performed by running: <pre> >> make runtest</pre> <p> If
  <strong>SSHT</strong> is installed correctly the test program should
  run and print test results to the terminal.  The test program
  performs an inverse (spin) spherical harmonic transform of a random
  signal, followed by a forward transform.  The error between the
  original and recovered spherical harmonic coefficients is computed
  and displayed.  All errors should be of the order of numerical
  precision.

  <p>Alternatively, you may run the test program directly by running:
  <pre> >> ./bin/c/ssht_test &ltbandlimit&gt &ltspin&gt</pre>
  <p> where <code>&ltbandlimit&gt</code> and <code>&ltspin&gt</code> are
  the harmonic band-limit and spin number, respectively, of your test.

  <p>To check the version and build numbers of your version run:
  <pre> >> ./bin/c/ssht_about </pre>

  <h4>Documentation</h4>

  <p>
  The <strong>SSHT</strong> code is self documenting.  Although the package
  ships with <a href="#documentation">source documentation</a>, you may generate html source
  documentation by running:
  <pre> >> make doc</pre>

  <p> Documentation is generated using <a
   href="http://www.doxygen.org">doxygen</a>, thus you must have doxygen
  installed on your system to generate the source documentation.


  <h4>Cleaning up</h4>

  <p> To clean up your version of the <strong>SSHT</strong> code and
  remove all builds run:
  <pre> >> make clean</pre>

  <p> To remove all source documentation run:
  <pre> >> make cleandoc</pre>
<br>

<!--------------------------------------------------------------->
<a name="documentation"><h2>Source code documentation</h2></a>

  <p>
  <strong>SSHT</strong> ships with source documentation that is
  generated by <a href="http://www.doxygen.org">doxygen</a>.
  Documentation is available here for the <a href="c/html/index.html">C</a>
and <a href="f90/html/index.html">Fortran 90</a> implementations.  The
  Matlab routines that interface with the C implementation are self
  documenting (documentation can be access through the help command in
  Matlab), as discussed below.  


<!--------------------------------------------------------------->
<a name="matlab"><h2>Matlab interface</h2></a>

  <p> Once the Matlab interface is built, you must have
  <code>ssht/src/matlab</code> in your path in order to run the Matlab functions.
  A number of Matlab functions and demos illustrating their use are
  provided.

  <h4>Functions</h4>

  <p>Usage of the <strong>SSHT</strong> Matlab interface will most
  frequently require only the functions to perform forward and inverse
  spherical harmonic transforms (<code>ssht_forward</code> and
  <code>ssht_inverse</code> respectively).  However, a number of
  additional functions are also provided.  A full list of Matlab
  functions, with brief descriptions are given here:

  <pre>

  <a href="../src/matlab/ssht_c2s.m">ssht_c2s</a>
  Convert cartesian to spherical coordinates

  <a href="../src/matlab/ssht_dl.m">ssht_dl</a>
  Compute Wigner small-d functions

  <a href="../src/matlab/ssht_dln.m">ssht_dln</a>
  Compute Wigner small-d functions for given n

  <a href="../src/matlab/ssht_elm2ind.m">ssht_elm2ind</a>
  Convert harmonic indices to vector index

  <a href="../src/matlab/ssht_forward.m">ssht_forward</a>
  Compute forward spin spherical harmonic transform

  <a href="../src/matlab/ssht_forward_adjoint.m">ssht_forward_adjoint</a>
  Compute adjoint forward spin spherical harmonic transform

  <a href="../src/matlab/ssht_ind2elm.m">ssht_ind2elm</a>
  Convert vector index to harmonic indices

  <a href="../src/matlab/ssht_inverse.m">ssht_inverse</a>
  Compute inverse spin spherical harmonic transform

  <a href="../src/matlab/ssht_inverse_adjoint.m">ssht_inverse_adjoint</a>
  Compute adjoint inverse spin spherical harmonic transform

  <a href="../src/matlab/ssht_plot_harmonic.m">ssht_plot_harmonic</a>
  Plot spherical harmonic coefficients

  <a href="../src/matlab/ssht_plot_mollweide.m">ssht_plot_mollweide</a>
  Plot function using Mollweide projection

  <a href="../src/matlab/ssht_plot_sphere.m">ssht_plot_sphere</a>
  Plot function on sphere

  <a href="../src/matlab/ssht_s2c.m">ssht_s2c</a>
  Convert spherical to cartesian coordinates

  <a href="../src/matlab/ssht_sampling.m">ssht_sampling</a>
  Compute sample positions
  </pre>

  <p> To access the documentation for each function in Matlab, simply
  run:
  <pre> >> help &ltfunction&gt</pre>
  <p> where <code>&ltfunction&gt</code> is the function name. 
  

  <h4>Demos</h4>

  <p> A number of demos are provided to illustrate the use of the
  Matlab interface.  The demos start extremely simple and
  progressively become more complicated/flexible.

  <pre>
  <a href="../src/matlab/ssht_demo0.m">ssht_demo0</a>
  Plot spherical harmonic functions on the sphere.

  <a href="../src/matlab/ssht_demo1.m">ssht_demo1</a>
  Simple demo to compute inverse and forward transform of complex
  scalar function, using simplest interface with default options.

  <a href="../src/matlab/ssht_demo2.m">ssht_demo2</a>
  Simple demo to compute inverse and forward transform of real scalar
  function, using simplest interface with default options.

  <a href="../src/matlab/ssht_demo3.m">ssht_demo3</a>
  Demo to compute inverse and forward transform of spin function,
  using standard interface with various options.

  <a href="../src/matlab/ssht_demo4.m">ssht_demo4</a>
  Demo to compute inverse and forward transform of spin function,
  using polar interface with various options.

  <a href="../src/matlab/ssht_demo5.m">ssht_demo5</a>
  Simulate a Gaussian cosmic microwave background (CMB).

  <a href="../src/matlab/ssht_demo6.m">ssht_demo6</a>
  Smooth Earth topography map by applying a Gaussian filter in
  harmonic space.

  <a href="../src/matlab/ssht_demo7.m">ssht_demo7</a>
  Integrate a band-limited function on the sphere using the
  symmetrised quadrature weights. 

  <a href="../src/matlab/ssht_demo8.m">ssht_demo8</a>
  Evaluate Wigner and spherical harmonic functions.
  </pre>

 <p> To access the documentation for each demo in Matlab, simply
  run:
  <pre> >> help &ltdemo&gt</pre>
  <p> where <code>&ltdemo&gt</code> is the demo name.

  <!--------------------------------------------------------------->
<a name="python"><h2>Python interface</h2></a>

  <p> Once the python interface is built, you must have
  <code>ssht/src/python</code> in your python path in order to run the python functions.
  A number of python functions and demos illustrating their use are
  provided.

  <h4>Functions</h4>

  <p>Usage of the <strong>SSHT</strong> python interface will most
  frequently require only the functions to perform forward and inverse
  spherical harmonic transforms (<code>pyssht.forward</code> and
  <code>pyssht.inverse</code> respectively).  However, a number of
  additional functions are also provided.  A full list of python
  functions are given <a href="../src/python/SSHT_Python_Documentation.md">here</a>.


  <h4>Demos</h4>

  <p> A number of demos are provided to illustrate the use of the
  python interface.  The demos start extremely simple and
  progressively become more complicated/flexible.

  <pre>
  <a href="../src/python/pyssht_demo_0.py">pyssht_demo_0</a>
  Plot spherical harmonic functions on the sphere.

  <a href="../src/python/pyssht_demo_1.py">pyssht_demo_1</a>
  Simple demo to compute inverse and forward transform of complex
  scalar function, using simplest interface with default options.

  <a href="../src/python/pyssht_demo_2.py">pyssht_demo_2</a>
  Simple demo to compute inverse and forward transform of real scalar
  function, using simplest interface with default options.

  <a href="../src/python/pyssht_demo_3.py">pyssht_demo_3</a>
  Demo to compute inverse and forward transform of spin function,
  using standard interface with various options.

  <a href="../src/python/pyssht_demo_4.py">pyssht_demo_4</a>
  Demo to compute inverse and forward transform of spin function,
  using polar interface with various options.

  <a href="../src/python/pyssht_demo_5.py">pyssht_demo_5</a>
  Smooth Earth topography map by applying a Gaussian filter in
  harmonic space.

  <a href="../src/python/pyssht_demo_6.py">pyssht_demo_6</a>
  Integrate a band-limited function on the sphere using the
  symmetrised quadrature weights.

  <a href="../src/python/pyssht_demo_7.m">pyssht_demo_7</a>
  Rotating an image on the sphere in harmonic space using the 
  Wigner matricies.
  </pre>

<!--------------------------------------------------------------->
<a name="download"><h2>Download</h2></a>

  <p>We make the source code of the <strong>SSHT</strong> package
  available under the license described <a
   href="#license">below</a>.

  <p><strong>SSHT</strong> can be downloaded from the following site:

  <p align=center>
  <a href="https://github.com/astro-informatics/ssht"> <img src="images/download_icon.gif"> </a>
  </p>

<!--------------------------------------------------------------->
<a name="referencing"><h2>Referencing</h2></a>

  <p> If you use <strong>SSHT</strong> for work that results in
  publication, please reference this site (<a
   href="http://www.jasonmcewen.org/">http://www.jasonmcewen.org/</a>)
  and our related academic paper:

<blockquote> J. D. McEwen and
 Y. Wiaux, <a href="http://www.jasonmcewen.org/publications.html#mcewen:fssht">A
 novel sampling theorem on the sphere</a>, IEEE Trans. Sig. Proc., 59(12):5876-5887, 2011 (<a href="http://arxiv.org/abs/1110.6298">ArXiv</a>
 | <a href="http://dx.doi.org/10.1109/TSP.2011.2166394">DOI</a>). </blockquote>

  <p> If you make use of our fast adjoint algorithms, then please also cite:

<blockquote> J. D. McEwen, G. Puy, J.-Ph. Thiran, P. Vandergheynst,
D. Van De Ville and Y. Wiaux, <a
 href="http://www.jasonmcewen.org/publications.html#mcewen:css2">Sparse image reconstruction on the sphere: implications of a new sampling theorem</a>, IEEE Trans. Image Proc.,
22(6):2275-2285, 2013 (<a href="http://arxiv.org/abs/1205.1013">ArXiv</a>
| <a href="http://dx.doi.org/10.1109/TIP.2013.2249079">DOI</a>).

</blockquote>


<!--------------------------------------------------------------->
<a name="version"><h2>Version</h2></a>

  <p>
  Version: 1.2b1<br>
  Release date: April 2018

  <h4>Version history</h4>
  <p>
 <ul>
   <li>1.2b1 (April 2018): Support for linking with C++.</li>
   <li>1.1b1 (April 2017): Python interface added and support for C99 standard.</li>
   <li>1.0b1 (31 October 2011): Public release of first beta.</li>
   <li>0.2 (20 May 2011): Fast adjoint algorithms added.</li>
   <li>0.1 (5 March 2011): First private release.</li>
  </ul>

<!--------------------------------------------------------------->
<a name="license"><h2>License</h2></a>

<blockquote>  
<p>
SSHT package to perform spin spherical harmonic transforms<br>
Copyright (C) 2011 Jason McEwen

<p>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

<p>
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details (<a href="../LICENSE.txt">LICENSE.txt</a>).

<p> 
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301, USA.
</blockquote>

<!--------------------------------------------------------------->
<a name="authors"><h2>About the authors</h2></a>

  <p> <strong>SSHT</strong> was initially written by <a href="http://www.jasonmcewen.org/">Jason McEwen</a>, based on collaborative work with <a href="http://www.google.co.uk/search?q=yves wiaux">Yves Wiaux</a>, but significant contributions have since been made by <a href="https://www.christophergrwallis.org/">Christopher Wallis</a>, Martin B&uuml;ttner, and <a href="http://ixkael.com/blog/">Boris Leistedt</a>.

<br><br><br><br>

</div>



<!--------------------------- FOOTER --------------------------->
<div id="footer">

  <p>
  <a href="#header">Back to top</a><br >
  
  <p>&copy; 2011 <a href="http://www.jasonmcewen.org">Jason McEwen</a> | Design by
  <a href="http://andreasviklund.com/">Andreas Viklund</a> </p>



</div>
</body>
</html>
